<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="testloader-objects.html" />
<link rel="prev" href="testsuite-objects.html" />
<link rel="parent" href="module-unittest.html" />
<link rel="next" href="testloader-objects.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>23.3.7 TestResult Objects </title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="23.3.6 testsuite Objects"
  href="testsuite-objects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="23.3 unittest  "
  href="module-unittest.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="23.3.8 testloader Objects"
  href="testloader-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="testsuite-objects.html">23.3.6 TestSuite Objects</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-unittest.html">23.3 unittest  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="testloader-objects.html">23.3.8 TestLoader Objects</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION0025370000000000000000"></a><a name="testresult-objects"></a>
<br>
23.3.7 TestResult Objects
            
</h2>

<p>
A <tt class="class">TestResult</tt> object stores the results of a set of tests.  The
<tt class="class">TestCase</tt> and <tt class="class">TestSuite</tt> classes ensure that results are
properly recorded; test authors do not need to worry about recording the
outcome of tests.

<p>
Testing frameworks built on top of <tt class="module"><a href="module-unittest.html">unittest</a></tt> may want
access to the <tt class="class">TestResult</tt> object generated by running a set of
tests for reporting purposes; a <tt class="class">TestResult</tt> instance is
returned by the <tt class="method">TestRunner.run()</tt> method for this purpose.

<p>
<tt class="class">TestResult</tt> instances have the following attributes that will
be of interest when inspecting the results of running a set of tests:

<p>
<dl><dt><b><tt id='l2h-5041' xml:id='l2h-5041' class="member">errors</tt></b></dt>
<dd>
  A list containing 2-tuples of <tt class="class">TestCase</tt> instances and
  strings holding formatted tracebacks. Each tuple represents a test which
  raised an unexpected exception.
  
<span class="versionnote">Changed in version 2.2:
Contains formatted tracebacks instead of
                  <tt class="function">sys.exc_info()</tt> results.</span>

</dl>

<p>
<dl><dt><b><tt id='l2h-5042' xml:id='l2h-5042' class="member">failures</tt></b></dt>
<dd>
  A list containing 2-tuples of <tt class="class">TestCase</tt> instances and strings
  holding formatted tracebacks. Each tuple represents a test where a failure
  was explicitly signalled using the <tt class="method">TestCase.fail*()</tt> or
  <tt class="method">TestCase.assert*()</tt> methods.
  
<span class="versionnote">Changed in version 2.2:
Contains formatted tracebacks instead of
                  <tt class="function">sys.exc_info()</tt> results.</span>

</dl>

<p>
<dl><dt><b><tt id='l2h-5043' xml:id='l2h-5043' class="member">testsRun</tt></b></dt>
<dd>
  The total number of tests run so far.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5044' xml:id='l2h-5044' class="method">wasSuccessful</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  Returns <tt class="constant">True</tt> if all tests run so far have passed,
  otherwise returns <tt class="constant">False</tt>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5045' xml:id='l2h-5045' class="method">stop</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
  This method can be called to signal that the set of tests being run
  should be aborted by setting the <tt class="class">TestResult</tt>'s <code>shouldStop</code>
  attribute to <tt class="constant">True</tt>.  <tt class="class">TestRunner</tt> objects should respect
  this flag and return without running any additional tests.

<p>
For example, this feature is used by the <tt class="class">TextTestRunner</tt> class
  to stop the test framework when the user signals an interrupt from
  the keyboard.  Interactive tools which provide <tt class="class">TestRunner</tt>
  implementations can use this in a similar manner.
</dl>

<p>
The following methods of the <tt class="class">TestResult</tt> class are used to
maintain the internal data structures, and may be extended in
subclasses to support additional reporting requirements.  This is
particularly useful in building tools which support interactive
reporting while tests are being run.

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5046' xml:id='l2h-5046' class="method">startTest</tt></b>(</nobr></td>
  <td><var>test</var>)</td></tr></table></dt>
<dd>
  Called when the test case <var>test</var> is about to be run.

<p>
The default implementation simply increments the instance's
  <code>testsRun</code> counter.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5047' xml:id='l2h-5047' class="method">stopTest</tt></b>(</nobr></td>
  <td><var>test</var>)</td></tr></table></dt>
<dd>
  Called after the test case <var>test</var> has been executed, regardless
  of the outcome.

<p>
The default implementation does nothing.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5048' xml:id='l2h-5048' class="method">addError</tt></b>(</nobr></td>
  <td><var>test, err</var>)</td></tr></table></dt>
<dd>
  Called when the test case <var>test</var> raises an unexpected exception
  <var>err</var> is a tuple of the form returned by <tt class="function">sys.exc_info()</tt>:
  <code>(<var>type</var>, <var>value</var>, <var>traceback</var>)</code>.

<p>
The default implementation appends <code>(<var>test</var>, <var>err</var>)</code> to
  the instance's <code>errors</code> attribute.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5049' xml:id='l2h-5049' class="method">addFailure</tt></b>(</nobr></td>
  <td><var>test, err</var>)</td></tr></table></dt>
<dd>
  Called when the test case <var>test</var> signals a failure.
  <var>err</var> is a tuple of the form returned by
  <tt class="function">sys.exc_info()</tt>:  <code>(<var>type</var>, <var>value</var>,
  <var>traceback</var>)</code>.

<p>
The default implementation appends <code>(<var>test</var>, <var>err</var>)</code> to
  the instance's <code>failures</code> attribute.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5050' xml:id='l2h-5050' class="method">addSuccess</tt></b>(</nobr></td>
  <td><var>test</var>)</td></tr></table></dt>
<dd>
  Called when the test case <var>test</var> succeeds.

<p>
The default implementation does nothing.
</dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="23.3.6 testsuite Objects"
  href="testsuite-objects.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="23.3 unittest  "
  href="module-unittest.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="23.3.8 testloader Objects"
  href="testloader-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="testsuite-objects.html">23.3.6 TestSuite Objects</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-unittest.html">23.3 unittest  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="testloader-objects.html">23.3.8 TestLoader Objects</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
